Add Steps concept and durable execution docs for AI Transport#3459
Conversation
|
Important Review skippedAuto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the ⚙️ Run configurationConfiguration used: Repository UI Review profile: CHILL Plan: Pro Run ID: You can disable this status message by setting the Use the checkbox below for a quick retry:
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Apply review feedback from PR #3459, correcting statements that diverged from actual SDK behaviour and house conventions. - Correct the retry-supersede edge case: a retry supersedes the prior attempt the moment it calls step.start(), because supersede keys on the fresh higher-serial ai-step-start under the same stepId, not on any output the retry produces. - Qualify Realtime-client sharing as same-process only; Temporal and Vercel Workflow DevKit isolate each activity in its own process, and clarify that session objects must not be shared across activities. - Use key: process.env.ABLY_API_KEY instead of authUrl in server-side and agent code samples, where an API key is the correct credential. - Reference session.end()/session.detach() rather than the non-existent session.close() on AgentSession. - Add 'cancelled' to the terminal StepEndReason list. - Use "realtime" (one word) per house style. - Align the AI Transport SDK version to the two-part '0.5' format used by sibling entries in languageData.ts.
There was a problem hiding this comment.
LGTM, there are still a couple of outdated AgentSession.close() references and StepEndReason not mentioning cancelled - I'm going to address it in my #3463 (see AI Transport docs: align session teardown and step end reasons with SDK commit)
Document the Step primitive and the durable-execution pattern that runs AI Transport agents inside a workflow engine. A Step is the re-attemptable unit of output within a Run; a retry under the same stepId supersedes the failed attempt on the channel rather than appending beside it, which is what makes a Run safe to execute across process boundaries and workflow retries. New pages: - concepts/steps: the Step model, lifecycle, and supersede-on-retry semantics, with a diagram. - features/durable-execution: adopt an in-flight Run from a fresh process, retry a failed Step under a stable stepId, close the Run on exhausted retries. - frameworks/temporal, getting-started/temporal: the reference workflow-engine integration, with the openRun / first-inference activity split and channel-routed cancels. - api/javascript/temporal: the stepIdFor helper. Extend agent-session API reference with adoptRun, createStep, detach, and RunStep. Add the ai-step-start / ai-step-end events and step headers to the wire protocol. Cross-link Steps and durable execution from the Runs, Sessions, tool-calling, reconnection, and going-to-production pages, and add nav entries. Promote durable execution to "Available today" on the roadmap.
A verbatim run-through of the Temporal getting-started guide in a fresh Next.js project surfaced compile and setup failures. Correct the guide and the pages it links to so a reader who follows it can build and run. - Pin the install command to the API's target release (@ably/ai-transport@^0.5.0) and the compatible AI SDK line (ai@^6, @ai-sdk/*@^3), and add deps the guide's own code uses but the command omitted: zod, tsx, jsonwebtoken, and the dev typings. - Add a "Set up the project" section: ESM package.json with the worker script, next.config serverExternalPackages for the Temporal client, and the required .env keys. - Type the guide's runInference activity (VercelAgentRun alias) so it compiles under strict TypeScript. - authentication: grant the conversations:* namespace so the token authorizes the channel clients actually open, define the referenced authenticateUser, type the handler, and guard ABLY_API_KEY. - vercel-ai-sdk: type the Providers component and Ably client state. - temporal API reference: drop the incidental "first activity is 1" sentence.
Apply review feedback from PR #3459, correcting statements that diverged from actual SDK behaviour and house conventions. - Correct the retry-supersede edge case: a retry supersedes the prior attempt the moment it calls step.start(), because supersede keys on the fresh higher-serial ai-step-start under the same stepId, not on any output the retry produces. - Qualify Realtime-client sharing as same-process only; Temporal and Vercel Workflow DevKit isolate each activity in its own process, and clarify that session objects must not be shared across activities. - Use key: process.env.ABLY_API_KEY instead of authUrl in server-side and agent code samples, where an API key is the correct credential. - Reference session.end()/session.detach() rather than the non-existent session.close() on AgentSession. - Add 'cancelled' to the terminal StepEndReason list. - Use "realtime" (one word) per house style. - Align the AI Transport SDK version to the two-part '0.5' format used by sibling entries in languageData.ts.
Clarify the auth guidance so agents stop rewriting valid server-side code, and add the "realtime" spelling rule that was previously only enforced by hand. - Principle 17 now states the client/server split explicitly: browser code uses authUrl, but server-side and agent code (activities, agent routes, workers) must use key: process.env.ABLY_API_KEY. An authUrl in a server snippet is a bug, not a pattern to preserve. - Note why the client-key verification grep passes process.env-sourced keys, so the exception is visible at the check itself. - Add "realtime" (one word) as an enforced spelling, with a sweep grep in the verification block.
f3bc49c to
da6473c
Compare
Document running the AI Transport SDK on Vercel Workflow Development Kit (Vercel WDK), the in-app durable-execution integration, alongside the existing Temporal one. - frameworks/workflow-devkit: how AI Transport composes with Vercel WDK. The workflow opens the Run and runs each model call and tool as its own WDK step, using the WDK step id as the AI Transport Step id so a retry supersedes the failed attempt on the channel rather than appending beside it. Covers the driver-owned tool loop for server, client-executed, and approval-gated tools, channel-routed cancels, and suspend and resume across workflows. - getting-started/workflow-devkit: a Next.js walkthrough that opens the Run and runs each inference as its own retryable step, with a flaky tool that shows a retry superseding the failed attempt on the channel. Add the two framework diagrams, nav entries under By SDK and Frameworks, and cross-links from the Steps, durable-execution, tool-calling, concepts, roadmap, going-to-production, and Temporal pages. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Two documentation-wide accuracy fixes against @ably/ai-transport v0.5.0.
AgentSession no longer has close(): teardown is end(), which closes any
still-open Run as `cancelled` then detaches. detach() alone is reserved for
durable cross-process handoff. Every agent-side example that tore down with
session.close() now uses session.end(), and the connections concept describes
the ClientSession/AgentSession teardown split correctly. Client-side
ClientSession.close() is unchanged.
StepEndReason is `complete` | `failed` | `cancelled`: a cancel arriving while a
Step is open closes ai-step-end{cancelled} before the Run ends. The Steps
concept, the AgentSession step-end reference (including the end() default
derivation), and the wire-protocol step-reason header and ai-step-end rows now
list all three. The Run-level run-reason (RunEndReason) is left as
complete/cancelled/error.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
A write-docs review pass over the Vercel WDK pages tightened wording and corrected two mechanism descriptions that misstated how the SDK behaves. On the framework page, the supersede explanation attributed the prompt-ordering guarantee to a "short wait" and said the publish ack does not guarantee it. The guarantee is awaiting step.start(): it folds the superseding, higher-serial ai-step-start into the read model behind run.view before it resolves, so reading the view straight after is already clean. The cancel edge case claimed a later cancel is replayed from channel history when load() resolves; cancels route only through the live channel subscription, so the text now matches the SDK and demo. The rest is phrasing: "realtime" spelling, a de-duplicated "owns its half of the job" metaphor, an active-voice bullet, and a fifth Explore-next link. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Apply review feedback from PR #3459, correcting statements that diverged from actual SDK behaviour and house conventions. - Correct the retry-supersede edge case: a retry supersedes the prior attempt the moment it calls step.start(), because supersede keys on the fresh higher-serial ai-step-start under the same stepId, not on any output the retry produces. - Qualify Realtime-client sharing as same-process only; Temporal and Vercel Workflow DevKit isolate each activity in its own process, and clarify that session objects must not be shared across activities. - Use key: process.env.ABLY_API_KEY instead of authUrl in server-side and agent code samples, where an API key is the correct credential. - Reference session.end()/session.detach() rather than the non-existent session.close() on AgentSession. - Add 'cancelled' to the terminal StepEndReason list. - Use "realtime" (one word) per house style. - Align the AI Transport SDK version to the two-part '0.5' format used by sibling entries in languageData.ts.
Document the Step primitive and the durable-execution pattern that runs AI Transport agents inside a workflow engine. A Step is the re-attemptable unit of output within a Run; a retry under the same stepId supersedes the failed attempt on the channel rather than appending beside it, which is what makes a Run safe to execute across process boundaries and workflow retries.
New pages:
concepts/steps: the Step model, lifecycle, and supersede-on-retry semantics, with a diagram.
features/durable-execution: adopt an in-flight Run from a fresh process, retry a failed Step under a stable stepId, close the Run on exhausted retries.
frameworks/temporal, getting-started/temporal: the reference workflow-engine integration, with the openRun / first-inference activity split and channel-routed cancels.
api/javascript/temporal: the stepIdFor helper.
Extend agent-session API reference with adoptRun, createStep, detach, and RunStep. Add the ai-step-start / ai-step-end events and step headers to the wire protocol. Cross-link Steps and durable execution from the Runs, Sessions, tool-calling, reconnection, and going-to-production pages, and add nav entries. Promote durable execution to "Available today" on the roadmap.